///////////////////////////////////////////////////////////////////////////////
//
//  Copyright (C) 2007-2009 ILOG, S.A.
//  All Rights Reserved.
//  The following is ILOG Source Code.  No modifications may be made to the  
//  ILOG Source Code.  Any usage of the ILOG Source Code is subject to 
//  the terms and conditions of the ILOG End User License Agreement   
//  applicable to this ILOG software product.
//
///////////////////////////////////////////////////////////////////////////////

package ilog.gauges.gaugesClasses.rectangular
{
  import ilog.gauges.gaugesClasses.IScale;

  /**
   * The <code>IRectangularScale</code> interface extends the <code>IScale</code>
   * interface for rectangular scales.
   *  
   * @see ilog.gauges.rectangular.RectangularGauge
   * 
   */    
  public interface IRectangularScale extends IScale
  {
    /**
     * The length of the scale, in pixels. This property is set by the 
     * <code>RectangularScaleRelatedRenderer</code> that is the master of the 
     * scale. It corresponds to the actual screen length of the master. It allows 
     * the scale to do proper computation to transform values into pixel 
     * positions with respect to the master length.
     * 
     * @default 0
     * 
     * @see ilog.gauges.gaugesClasses.rectangular.RectangularScaleRelatedRenderer#master
     */      
    function get length():Number;
    
    /**
     * @private
     */
    function set length(value:Number):void;
    
    /**
     * The offset of the scale, in pixels. This property is set by the 
     * <code>RectangularScaleRelatedRenderer</code> that is the master of the 
     * scale. It corresponds to the pixel offset that is present at the origin of 
     * the master, before its content actually starts. It allows the scale to 
     * do proper computation to transform values into pixel positions.
     * 
     * @default 0
     * 
     * @see #length
     */
    function get offset():Number;
    
    /**
     * @private
     */
    function set offset(value:Number):void;
    
    /**
     * Transforms a value into a pixel position according to <code>length</code> 
     * and <code>offset</code> values.
     * 
     * @param value A data value to compute the corresponding position. It is commonly a Number or a String.
     * 
     * @return The corresponding position in pixels. 
     */      
    function positionForValue(value:Object):Number;
    
    /**
     * Transforms a pixel position into a value according to <code>length</code> and
     * <code>offset</code> values.
     * 
     * @param position A position to compute the corresponding value.
     * 
     * @return The corresponding value. 
     */ 
    function valueForPosition(position:Number):Object;    
    
    /**
     * This function returns <code>true</code> if the position parameter
     * is between the scale accepted positions (that is, between <code>offset</code>
     * and <code>length + offset</code>).
     * 
     * @param position A position.
     * 
     * @return <code>true</code> if the position is in the scale interval.  
     */     
    function positionInRange(position:Number):Boolean;
  }
}
